tiny-c system library.html - lrb - 1/11/9

Source: pp 97-101 of Scott B. Guthery's book "Learning C with tiny-c" 1985 TAB Books Inc. - additions by Lee Bradley

The tiny-c system library

The system library includes functions that do input, output and character manipulation. The definitions given here show the declaration of the function name and the arguments, if any.

It's time for a digression ...

An important and interesting feature of tiny-c is the Machine Call (MC). There are two kinds, "system" and "user." Machine Calls are used for speed and/or to interface with special input/output devices.

Many of the functions in the tiny-c system library are "system" Machine Calls which have been "wrapped" using names which make them more easily understood. Machine Calls are coded in "machine language" (i.e. in assembly language or in C and then assembled or compiled). There is a set furnished with tiny-c. See tiny-c machine calls for the details.

Machine Calls have an awkward, undescriptive syntax. For example, it isn't immediately obvious what

MC(47,64,1,1001)

might mean or do. It is customary to wrap a Machine Call up with a nice name, like this:

plot int r,c,nf  [
  return MC(r,c,nf,1001)
  ]

Now you could write programs that say

plot(47,64,1)

and, although we haven't defined the plot function yet, plot is certainly more suggestive of what it does than MC 1001.

Every addition to a machine call library should be accompanied by an entry in one of the tiny-c libraries. You would place MC 1001 in the user machine call library, and plot would be placed in a personal library of tiny-c functions.

That's it for the digression. On to the tiny-c system library functions.

gs char buffer(0)

Reads a line, i.e., a string of characters terminated by a carriage return, from the terminal and puts it in buffer. The carriage return at the end of the line is changed to a null byte. The value of the function is the number of characters placed in buffer excluding the null byte. A value of 0 is permitted.

ps char buffer(0)

Prints the string in buffer on the screen. A null byte signals the end of the string. The null is not transmitted. The number of characters transmitted is returned as the value of the function.

pl char buffer(0)

The same as ps but prints the string on a new line. The number of characters transmitted, not including the leading return and line feed, is returned.

pn int n

Prints the value of n on the screen preceded by a blank. The number of characters transmitted, including the blank, is returned.

gn

Reads a line and returns the integer at the beginning of the line. If there is no integer there, it prints "number required " and tries again.

gc

Reads a line and returns the first character on the line.

putchar char c

Transmits the character c to the terminal. Any character, including control characters, can be transmitted, except that a quote is transmitted if c is null. The character c is returned.

getchar

Reads and returns a character from the terminal. Any character, including control characters, can be read by this function.

readfile char name(0),where(0),limit(0);int unit

Reads data from a file. The name argument is a character string terminated by a null byte; where and limit are pointers. The unit designator is an input/output unit number. The file with name name is opened for reading on device unit. All of its records are read and placed in sequentially higher addresses, starting at where but in no case going beyond limit. Then unit is closed. If successful, the total number of bytes read is returned. If limit is exceeded, the message "Too big" is printed and -2 is returned.

writefile char name(0),from(0),to(0);int unit

Writes data to a file. The name argument is a character string terminated by a null byte; from and to are pointers. The unit argument is an input/output unit number. Function writefile opens unit unit for output. The contents of sequentially higher addresses from from to to inclusive are written to unit as a file named name. Then the file is closed. If successful, the total number of bytes written is returned. If a problem occurs, a negative value is returned.

num char b(5);int v(0)

Converts a string of digits without leading sign or blanks to the corresponding numeric value, which is put in v(0). The first non-digit stops the conversion. At most, five digits are examined. The number of bytes converted is returned as the value of the function. Note that the second argument must be a pointer to an integer.

atoi char b(0);int v(0)

Converts a character string of this form:

  0 or more blanks
  optional + or - character
  0 or more blanks
  0 to 5 digits

to its numeric value, which is put in v(0). The first non-digit following the digit part stops the conversion. The number of characters in b that were used to form the value is returned as the value of the function.

ceqn char a(0),b(0);int n

Compares two character strings for equality for n characters. Returns 1 on equals, 0 on not-equals.

alpha char c

Returns a 1 if c is an alphabetic character, upper- or lowercase. Otherwise returns a 0.

index char s1(0);int n1;char s2(0);int n2

Finds the leftmost copy of the character string s2, which is n2 bytes long, in the character string s1, which is n1 bytes long. If s2 does not appear in s1, 0 is returned. If s2 does appear, returns n+1 such that s1+n points to the first character of the copy in s1.

move char a(0),b(0)

Moves string a into b up to and including the null byte of a.

movebl char a(0),b(0);int k

Moves a block of storage up or down k bytes in memory; a and b point to the first and last characters of the block to be moved. If k is positive, the move is to higher addresses, and if it is negative the move is to lower addresses. If k is positive, the byte at b is moved first, then the byte at b-1, etc. If k is negative, the byte at a is moved first. Large blocks thus can be moved a few bytes without destruction.

countch char a(0),b(0),c

Counts the instances of the character c in the block of storage from a to b inclusive and returns the count.

scann char from(0),to(0),c;int n(0)

Scans from from to to inclusive for instances of the character c. The integer n(0) is decremented for each c found. If n(0) reaches 0, or if the character in to(0) is examined, scann stops. Function scann returns the offset relative to the pointer from to the last examined character. Thus, if the third character position after from is the last examined, scann returns 3.

chrdy

Returns a copy of an input character from the terminal if a character has been typed but not yet read by another function, except that if the typed character is a null, a 1 is returned. If no unread character has been typed, a null byte is returned. The character is not cleared so a subsequent call to getchar or gc will return the same character. Note: chrdy does nothing in the Linux version.

pft char a(0),b(0)

Transfers all characters from a to b inclusive to the screen.

fopen int rw;char name(0);int size,unit

Opens or creates a file for access on logical unit number unit. The name variable contains a null-terminated string giving the name of the file. The file is opened for reading if rw is 1, and writing if rw is 2. If rw is 2 and the file does not exist, then it will be created and its size guaranteed to be at least size bytes. Otherwise size is ignored, but it must be given. If no error is detected, a 0 is returned. If an error is detected, a nonzero value is returned.

fread char a(0);int unit

Starting at a, reads into memory the next 512-byte record of data from the file opened on unit number unit. The array a must be large enough to hold an entire record. The length in bytes of the record actually placed at a is returned as the value of fread. A value of -1 is returned if an end-of-file is detected.

fwrite char from(0),to(0);int unit

Writes one record with the bytes from from to to inclusive to the file opened on unit number unit. This becomes the next record of the file. Its length is to-from+1; this is the length that will be returned when the record is read by fread.

fclose int unit

The file opened on unit number unit is made permanent and arrangements are made for end-of-file detection by fread.

beep int f,d

The internal PC speaker is sounded at frequency f for d tenths of a second. Note: This works in the PC/DOS version. It does nothing in the Linux version.

The remaining functions were added to those that appear in Guthery's book. One of the most interesting features of tiny-c is that you are free to add functions to the system library. We include the tiny-c source for these functions to show you how they were written.

cnormal [MC 1000]

Set the text cursor to "normal." This function is implemented differently in the Linux version (and the "normal" cursor is different).

chide [MC 1001]

Hide the text cursor.

csolid [MC 1002]

Set the text cursor to a solid block. This function does nothing in the Linux version.

cls[MC '\'-'A',1;MC '\'-1,1;MC '2',1;MC 'J',1;posc 1,1]

Clears the screen and homes the cursor. This and the next few functions only work in the PC/DOS interpreter if ANSI.COM (or equivalent) is loaded. The Linux terminal programs have native ANSI support.

color char c[MC '\'-'A',1;MC '\'-1,1;MC '3',1;MC c,1;MC 'm',1]

Sets the foreground color to white if c is '7', blue if c is '4' etc. The complete color chart follows:

'0'=black '1'=red '2'=green '3'=yellow '4'=blue '5'=magenta '6'=cyan '7'=white

posc int r,c[int R,C;R=25;C=80
if((r>=1)*(r<=R)*(c>=1)*(c<=C)==0)return 1
MC '\'-'A',1;MC '\'-1,1;pos r;MC ';',1;pos c;MC 'H',1;return 0
]

Positions the cursor at row r, column c.

pos int rc[if(rc>9)[MC rc/10+48,1;rc=rc%10]
MC rc+48,1
]

This is a helper function for posc.

hilo char c[MC '\'-'A',1;MC '\'-1,1;MC c,1;MC 'm',1]

Sets the text to "bright" if c is '1' or "dim" if c is '0'.

off [chide]

This and the next two functions are aliases for the corresponding functions discussed above.

on [cnormal]

solid[csolid]

version [return MC 1003]

This only works in the PC/DOS interpreter. It returns the version number of the interpreter.

int last,seed
random int low,high[int range;if(!last)last=seed=99
range=high-low+1;last=last*seed;if(last<0)last=-last
return low+(last/7)%range
]

Note the global variables last and seed. This returns a "random number" between low and high.

strlen char st(0)[int i;while(st(i))++i;return i]

This returns the length of string st.

strcat char s(0),t(0)[int i,j;i=strlen(s)
while(t(j))[s(i)=t(j);++i;++j];s(i)=0]

This concatenates string t onto string s.

strcpy char s(0),t(0)[
int i;while((s(i)=t(i)))++i
]

This copies string t into string s.

sak[pl"Press Enter ... ";return getchar]

Displays "Press Enter ..." (w/o the quotes) and waits for you to hit the Enter key.

exit[MC 10]

Causes an exit from the interpreter back to the operating system.

tolower char s(0)[int i;for(i=0;i='A')*(s(i)<='Z'))s(i)=s(i)+' '
]

Lowercases all characters in string s.

toupper char s(0)[int i;for(i=0;i='a')*(s(i)<='z'))s(i)=s(i)-' '
]

Uppercases all characters in string s.

memset char s(0);int b;char c[MC s,b,c,16]

Sets all bytes in memory starting at address s and going for b bytes to character c.